home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / System / ReqToolsLib / Source / reqtools / rtreqhandlera.c < prev    next >
Encoding:
C/C++ Source or Header  |  2001-07-02  |  4.5 KB  |  160 lines
  1.  
  2. /*
  3.     (C) 1999 - 2000 AROS - The Amiga Research OS
  4.     $Id: rtreqhandlera.c,v 1.5 2001/04/12 09:11:46 iaint Exp $
  5.  
  6.     Desc:
  7.     Lang: English
  8. */
  9.  
  10. #include <exec/types.h>
  11. #include <proto/exec.h>
  12. #include <proto/reqtools.h>
  13. #include <proto/intuition.h>
  14. #include <exec/libraries.h>
  15. #include <exec/memory.h>
  16. #include <aros/libcall.h>
  17.  
  18. #include "general.h"
  19. #include "reqtools_intern.h"
  20. #include "rtfuncs.h"
  21.  
  22. /*****************************************************************************
  23.  
  24.     NAME */
  25.  
  26.     AROS_LH3(ULONG, rtReqHandlerA,
  27.  
  28. /*  SYNOPSIS */
  29.  
  30.     AROS_LHA(struct rtHandlerInfo *, handlerinfo, A1),
  31.     AROS_LHA(ULONG, sigs, D0),
  32.     AROS_LHA(struct TagItem *, taglist, A0),
  33.  
  34. /*  LOCATION */
  35.  
  36.     struct ReqToolsBase *, ReqToolsBase, 18, ReqTools)
  37.  
  38. /*  FUNCTION
  39.     This function should be called if you used the RT_ReqHandler tag
  40.     with a requester function.
  41.  
  42.     The requester you used the tag with will have returned immediately
  43.     after its initialization and will have initialized a pointer to a
  44.     rtHandlerInfo structure for you. You should now do the following:
  45.  
  46.     Check the DoNotWait field. If it is FALSE you have to wait for the
  47.     signals in the WaitMask field (plus your own signals if you like).
  48.     If any of the signals in WaitMask are received or DoNotWait was not
  49.     FALSE you have to call rtReqHandlerA() and check its return value
  50.     for one of the following values:
  51.  
  52.     CALL_HANDLER - Check DoNotWait again, Wait() if you have to and
  53.         call rtReqHandlerA() again. In other words, loop.
  54.     everything else - normal return value, requester has finished. This
  55.         return value will be the same as if the requester had run
  56.         normally.
  57.  
  58.     You must pass the signals you received to rtReqHandlerA().
  59.  
  60.     NOTE: if you want to wait for your own signals do not do so if
  61.         DoNotWait is TRUE. Call rtReqHandlerA() and if you must know if
  62.         one of your signals arrived use SetSignal() to find this out.
  63.         If you are waiting for a message to arrive at a message port
  64.         you can simple call GetMsg() and check if it is non-null.
  65.         DoNotWait will naturally only be TRUE when it absolutely,
  66.         positively has to be. A multitasking machine as the Amiga
  67.         should use Wait() as much as possible.
  68.  
  69.     This is an example of a "requester loop":
  70.  
  71.     ...
  72.     struct rtHandlerInfo *hinfo;
  73.     ULONG ret, mymask, sigs;
  74.  
  75.     ...
  76.     // calculate our mask 
  77.     mymask = 1 << win->UserPort->mp_SigBit;
  78.  
  79.     // We use the RT_ReqHandler tag to cause the requester to return
  80.     // after initializing.
  81.     // Check the return value to see if this setup went ok.
  82.     if( rtFontRequest( req, "Font", RT_ReqHandler, &hinfo, TAG_END )
  83.                                                    == CALL_HANDLER )
  84.     {
  85.         do
  86.         {
  87.             // Wait() if we can 
  88.             if( !hinfo->DoNotWait )
  89.             {
  90.                 sigs = Wait( hinfo->WaitMask | mymask );
  91.             }
  92.             
  93.             // check our own message port 
  94.             while( msg = GetMsg( win->UserPort ) )
  95.             {
  96.                 ...
  97.                 // here we handle messages received at our windows
  98.                 // IDCMP port
  99.                 ...
  100.             }
  101.  
  102.             // let the requester do its thing (remember to pass 'sigs') 
  103.             ret = rtReqHandler( hinfo, sigs, TAG_END );
  104.  
  105.             // continue this loop as long as the requester is up
  106.         } while( ret == CALL_HANDLER )
  107.  
  108.         // when we get here we know the requester has finished, 'ret'
  109.         // is the return code.
  110.         ...
  111.         }
  112.     else
  113.     {
  114.         notify( "Error opening requester!" );
  115.     }
  116.     ...
  117.    
  118.     INPUTS
  119.     handlerinfo - pointer to handler info structure initialized by
  120.         using the RT_ReqHandler tag when calling a requester function.
  121.     sigs - the signals received by previous wait, will be ignored if
  122.         handlerinfo->DoNotWait was TRUE.
  123.     taglist - pointer to a TagItem array.
  124.  
  125.     TAGS
  126.     RTRH_EndRequest - supplying this tag will end the requester. The
  127.         return code from rtReqHandlerA() will _not_ be CALL_HANDLER,
  128.         but the requester return code. If the tagdata of this tag is
  129.         REQ_CANCEL the requester will be canceled, if it is REQ_OK the
  130.         requester will be ok-ed. In case of an EZRequest tagdata should
  131.         be the return code of the requester (TRUE, FALSE or 2,3,4,...).
  132.  
  133.     RESULT
  134.     ret - CALL_HANDLER if you have to call rtReqHandlerA() again, or
  135.         the normal return value from the requester.
  136.  
  137.     NOTES
  138.  
  139.     EXAMPLE
  140.  
  141.     BUGS
  142.     none known
  143.  
  144.     SEE ALSO
  145.     rtEZRequest() (RT_ReqHandler explanation)
  146.  
  147.     INTERNALS
  148.  
  149.     HISTORY
  150.  
  151. ******************************************************************************/
  152. {
  153.     AROS_LIBFUNC_INIT
  154.  
  155.     return RTFuncs_rtReqHandlerA(handlerinfo, sigs, taglist);
  156.         
  157.     AROS_LIBFUNC_EXIT
  158.     
  159. } /* rtReqHandlerA */
  160.